home *** CD-ROM | disk | FTP | other *** search
/ Cream of the Crop 25 / Cream of the Crop 25.iso / bbs / fido10as.zip / FIDOADDR.DOC < prev    next >
Text File  |  1997-04-08  |  8KB  |  174 lines
  1. fido_address
  2. =============================================================================
  3.  
  4.     This class implements a non-view parser for manipulating FidoNet(tm)
  5.     style network addresses. It is fully compliant with the FTSC-001
  6.     standard and also supports full 4D addressing with zones and points.
  7.     As an added bonus, this class supports 5D addressing with domains as
  8.     well.
  9.  
  10.     The class is quite intelligent as is able to recognize several valid
  11.     addresses with otherwise missing parts. For example, all of the
  12.     addresses listed below will be parsed correctly (they are valid):
  13.  
  14.                       1:383/47.0@fidonet.org
  15.                       1:383/47@fidonet.org
  16.                       383/47.0@fidonet.org
  17.                       383/47@fidonet.org
  18.                       1:383/47.0
  19.                       1:383/47
  20.                       383/47.0
  21.                       383/47
  22.                       47.0
  23.                       47
  24.  
  25.     As you can see, only one of the fields must be present in order for
  26.     an address specification to be considered valid. This is the node
  27.     numbers. The general format used by FidoNet-type technology is as
  28.     follows:
  29.  
  30.                         zone:net/node.point@domain
  31.  
  32.     Any of the fields can be omitted except for the node designation.
  33.     This class uses integers to represent all the numbers, so there will
  34.     be no problem with high zone designations (some software incorrectly
  35.     limits the zone numbers to less than 256).
  36.  
  37.  
  38.     FIDO_ADDRESS::FIDO_ADDRESS
  39.     -------------------------------------------------------------------------
  40.  
  41.         Summary   Various constructors for the object
  42.  
  43.         Syntax    fido_address();
  44.                   fido_address(int zone, int node, int net, int point);
  45.                   fido_address(int zone, int node, int net, int point,
  46.                                const char *domain);
  47.                   fido_address(const fido_address &addr);
  48.                   fido_address(const char *ascii_address);
  49.  
  50.         Remarks   These constructors allow several different ways of
  51.                   initializing the object. The first and simplest one will
  52.                   only set the internal fields to 0 (note that this will
  53.                   form an invalid address). The second and third ones will
  54.                   construct an object with values supplied by the user. The
  55.                   fourth version is the copy constructor which will create
  56.                   a fido_addres object from another already existing one.
  57.                   The last constructor is probably the most interesting as
  58.                   this is the one that actually parses an address stored in
  59.                   a string. The string must contain the address only, no
  60.                   whitespace or extraneous characters are permissible. As
  61.                   indicated in the introductory notes, all legal formats will
  62.                   be recognized and parsed by this routine. Fields that do
  63.                   not exist in the address will be set to 0.
  64.  
  65.         Return    n/a
  66.  
  67.  
  68.     FIDO_ADDRESS::SET_ZONE, SET_NET, SET_NODE, SET_POINT, SET_DOMAIN
  69.     -------------------------------------------------------------------------
  70.  
  71.         Summary   Set manually the different address portions
  72.  
  73.         Syntax    void set_zone(int zone);
  74.                   void set_net(int net);
  75.                   void set_node(int node);
  76.                   void set_point(int point);
  77.                   void set_domain(const char *domain);
  78.  
  79.         Remarks   These routines are fairly intuitive and should be used
  80.                   when there is a need to modify the address values stored
  81.                   in the object. No error-checking is performed. You might
  82.                   want to use these after parsing an address which has one
  83.                   or more parts missing. Since all missing parts will be
  84.                   set to 0 by the parser, they are readily identifiable and
  85.                   can be modified as necessary.
  86.  
  87.         Return    Nothing
  88.  
  89.  
  90.     FIDO_ADDRESS::SPLIT
  91.     -------------------------------------------------------------------------
  92.  
  93.         Summary   Parse an address from a string
  94.  
  95.         Syntax    void split(const char *address);
  96.  
  97.         Remarks   This routine is actually used by the constructor which
  98.                   parses a string with the address. Same restrictions apply
  99.                   here too. Use this routine when you want to dynamically
  100.                   change the object contents with another string address
  101.                   (thereby eliminating the need for additional objects).
  102.  
  103.         Return    Nothing
  104.  
  105.  
  106.     FIDO_ADDRESS::OPERATOR=
  107.     -------------------------------------------------------------------------
  108.  
  109.         Summary   Assigns one object to another
  110.  
  111.         Syntax    fido_address& operator=(const fido_address& addr);
  112.  
  113.         Remarks   The assignment operator is very intuitive and it does
  114.                   exactly what you would expect it to do. It takes the
  115.                   'addr' object and copies its values to the rvalue object
  116.                   which invoked the operator.
  117.  
  118.         Return    Reference to the calling object
  119.  
  120.  
  121.     FIDO_ADDRESS::ZONE, NET, NODE, POINT, DOMAIN
  122.     -------------------------------------------------------------------------
  123.  
  124.         Summary   Return the values of address parts
  125.  
  126.         Syntax    int   zone() const;
  127.                   int   net() const;
  128.                   int   node() const;
  129.                   int   point() const;
  130.                   char* domain(char *buf) const;
  131.  
  132.         Remarks   These accessors can be used to retrieve any single part
  133.                   of the address stored in the object. Special note regarding
  134.                   the domain() method is that the 'buf' parameter is
  135.                   required as this is where the domain string will be copied
  136.                   to. It should be big enough to accomodate it (a reasonable
  137.                   limit of 256 characters should be adequate).
  138.  
  139.         Return    Each function returns the respective part of the address.
  140.                   domain() returns the pointer supplied to it.
  141.  
  142.  
  143.     FIDO_ADDRESS::MERGE, MERGE2D, MERGE3D, MERGE4D, MERGE5D
  144.     -------------------------------------------------------------------------
  145.  
  146.         Summary   Create string representation of the address
  147.  
  148.         Syntax    char* merge(char *buf) const;
  149.                   char* merge2d(char *buf) const;
  150.                   char* merge3d(char *buf) const;
  151.                   char* merge4d(char *buf) const;
  152.                   char* merge5d(char *buf) const;
  153.  
  154.         Remarks   These functions will merge the address information into
  155.                   a valid FidoNet-style string. They all expect 'buf' which
  156.                   is supplied by the user to be large enough to accomodate
  157.                   the resulting string. No error-checking is performed. A
  158.                   buffer size of 256 characters should be adequate for most
  159.                   needs. The merge() method will create a string with the
  160.                   maximum number of available parts (all portions which are
  161.                   0 will be omitted, except for the node). The merge2d()
  162.                   routine will always produce a net/node combination
  163.                   regardless of the values. The merge3d() function will
  164.                   always produce the zone:net/node string regardless of the
  165.                   actual values. merge4d() will produce the full and most
  166.                   common format of zone:net/node.point regardless of the
  167.                   individual values. Finally, merge5d() will produce the
  168.                   full 5D address if a domain name is specified, otherwise,
  169.                   it will return the same result as merge4d(). This is the
  170.                   preferred method to use.
  171.  
  172.         Return    Pointer to the supplied buffer
  173.  
  174.